package edu.cs.usask.ca.silver.api.businesslogic;

import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;

import edu.cs.usask.ca.silver.api.persistence.StorageI;
import edu.cs.usask.ca.silver.businesslogic.ids.FileID;
import edu.cs.usask.ca.silver.businesslogic.ids.ModelVersionID;
import edu.cs.usask.ca.silver.businesslogic.ids.ScenarioCollectionID;
import edu.cs.usask.ca.silver.businesslogic.ids.ScenarioID;

/**
 * @author Team Bronze (Daniel Funk)
 * 
 *         Specification of the interface for the scenario collection bean.
 */
public interface ScenarioCollectionI {

	/**
	 * Adds a scenario collection to the storage layer
	 * 
	 * @param scName
	 *            Scenario collection name
	 * @param scCreator
	 *            Collection creator
	 * @param scDescr
	 *            Collection description
	 * @param mvId
	 *            Parent Model Version ID
	 * @param storage TODO
	 * @return A unique ScenarioCollectionID
	 * @throws Exception
	 */
	public ScenarioCollectionID createScenarioCollection(String scName,
			String scCreator, String scDescr, ModelVersionID mvId, StorageI storage)
			throws Exception;

	/**
	 * Returns a string containing the XML representation (non-recursive) of a
	 * scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return String containing the XML representation
	 * @throws Exception
	 */
	public String getScenarioCollectionAsXML(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Returns the name of a scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return The collection name
	 * @throws Exception
	 */
	public String getName(ScenarioCollectionID scId, StorageI storage) throws Exception;

	/**
	 * Returns the description of a scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return The collection description
	 * @throws Exception
	 */
	public String getDescription(ScenarioCollectionID scId, StorageI storage) throws Exception;

	/**
	 * Returns the creator of a scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return Scenario Collection creator
	 * @throws Exception
	 */
	public String getCreator(ScenarioCollectionID scId, StorageI storage) throws Exception;

	/**
	 * Returns the creation date of a scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return The creation date
	 * @throws Exception
	 */
	public Date getCreationDate(ScenarioCollectionID scId, StorageI storage) throws Exception;

	/**
	 * Returns the creation time of a scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return The creation time
	 * @throws Exception
	 */
	public Date getCreationTime(ScenarioCollectionID scId, StorageI storage) throws Exception;

	/**
	 * Returns the unique ModelVersionID of the version this collection belongs
	 * to
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return A unique ModelVersionID of the parent version
	 * @throws Exception
	 */
	public ModelVersionID getParentModelVersionId(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Returns an Array of ScenarioIDs of all scenarios contained in the
	 * scenario collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return Array of child ScenarioIDs
	 * @throws Exception
	 */
	public ScenarioID[] getScenarioIds(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Returns an array of FileIDs of all files associated with this scenario
	 * collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return Array of fileIDs of all file associated with this collection
	 * @throws Exception
	 */
	public FileID[] getAssociatedFileIds(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Returns an array of file names for the scenario collection associated
	 * files
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return Array of file names
	 * @throws NullPointerException
	 */
	public ArrayList<String> getAssociatedFileName(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Returns a HashMap of ScenarioIDs and Scenario names of all scenarios
	 * belonging to this collection
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return HashMap of ScenarioIDs and strings containing the scenario names
	 * @throws Exception
	 */
	public HashMap<ScenarioID, String> getScenarios(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Returns the unique ScenarioID of the most recently created Scenario
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return The ScenarioID of the most recently created scenario
	 * @throws Exception
	 */
	public ScenarioID getMostRecentScenarioId(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Update the name of a scenario collection in the storage layer
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param name
	 *            The (new) scenario collection name
	 * @param storage TODO
	 * @return TODO
	 * @throws Exception
	 */
	public boolean setName(ScenarioCollectionID scId, String name, StorageI storage)
			throws Exception;

	/**
	 * Update the description of a Scenario Collection in the storage layer
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param description
	 *            The (new) description of the collection
	 * @param storage TODO
	 * @return TODO
	 * @throws Exception
	 */
	public boolean setDescr(ScenarioCollectionID scId, String description, StorageI storage)
			throws Exception;

	/**
	 * Removes a scenario collection from storage
	 * 
	 * @param scId
	 *            A unique ScenarioCollectionID
	 * @param storage TODO
	 * @return TODO
	 * @throws Exception
	 */
	public boolean deleteScenarioCollection(ScenarioCollectionID scId, StorageI storage)
			throws Exception;

	/**
	 * Duplicate a scenario from another scenario
	 * 
	 * @param sId
	 *            A unique ScenarioID
	 * @param scId
	 *            A unique ScenarioCollectionID of the destination scenario
	 *            collection
	 * @param storage TODO
	 * 
	 * @return A unique ScenarioID of the duplicated scenario
	 */
	public ScenarioID duplicateScenario(ScenarioID sId,
			ScenarioCollectionID scId, StorageI storage) throws Exception;
}
